/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.avro.io;

import java.io.Flushable;
import java.io.IOException;
import java.nio.ByteBuffer;

import org.apache.avro.util.Utf8;

/**
 * Low-level support for serializing Avro values.
 * <p/>
 * This class has two types of methods. One type of methods support the writing
 * of leaf values (for example, {@link #writeLong} and {@link #writeString}).
 * These methods have analogs in {@link Decoder}.
 * <p/>
 * The other type of methods support the writing of maps and arrays. These
 * methods are {@link #writeArrayStart}, {@link #startItem}, and
 * {@link #writeArrayEnd} (and similar methods for maps). Some implementations
 * of {@link Encoder} handle the buffering required to break large maps and
 * arrays into blocks, which is necessary for applications that want to do
 * streaming. (See {@link #writeArrayStart} for details on these methods.)
 * <p/>
 * {@link EncoderFactory} contains Encoder construction and configuration
 * facilities.
 * 
 * @see EncoderFactory
 * @see Decoder
 */
public abstract class Encoder implements Flushable {

  /**
   * "Writes" a null value. (Doesn't actually write anything, but advances the
   * state of the parser if this class is stateful.)
   * 
   * @throws AvroTypeException If this is a stateful writer and a null is not
   *                           expected
   */
  public abstract void writeNull() throws IOException;

  /**
   * Write a boolean value.
   * 
   * @throws AvroTypeException If this is a stateful writer and a boolean is not
   *                           expected
   */
  public abstract void writeBoolean(boolean b) throws IOException;

  /**
   * Writes a 32-bit integer.
   * 
   * @throws AvroTypeException If this is a stateful writer and an integer is not
   *                           expected
   */
  public abstract void writeInt(int n) throws IOException;

  /**
   * Write a 64-bit integer.
   * 
   * @throws AvroTypeException If this is a stateful writer and a long is not
   *                           expected
   */
  public abstract void writeLong(long n) throws IOException;

  /**
   * Write a float.
   * 
   * @throws IOException
   * @throws AvroTypeException If this is a stateful writer and a float is not
   *                           expected
   */
  public abstract void writeFloat(float f) throws IOException;

  /**
   * Write a double.
   * 
   * @throws AvroTypeException If this is a stateful writer and a double is not
   *                           expected
   */
  public abstract void writeDouble(double d) throws IOException;

  /**
   * Write a Unicode character string.
   * 
   * @throws AvroTypeException If this is a stateful writer and a char-string is
   *                           not expected
   */
  public abstract void writeString(Utf8 utf8) throws IOException;

  /**
   * Write a Unicode character string. The default implementation converts the
   * String to a {@link org.apache.avro.util.Utf8}. Some Encoder implementations
   * may want to do something different as a performance optimization.
   * 
   * @throws AvroTypeException If this is a stateful writer and a char-string is
   *                           not expected
   */
  public void writeString(String str) throws IOException {
    writeString(new Utf8(str));
  }

  /**
   * Write a Unicode character string. If the CharSequence is an
   * {@link org.apache.avro.util.Utf8} it writes this directly, otherwise the
   * CharSequence is converted to a String via toString() and written.
   * 
   * @throws AvroTypeException If this is a stateful writer and a char-string is
   *                           not expected
   */
  public void writeString(CharSequence charSequence) throws IOException {
    if (charSequence instanceof Utf8)
      writeString((Utf8) charSequence);
    else
      writeString(charSequence.toString());
  }

  /**
   * Write a byte string.
   * 
   * @throws AvroTypeException If this is a stateful writer and a byte-string is
   *                           not expected
   */
  public abstract void writeBytes(ByteBuffer bytes) throws IOException;

  /**
   * Write a byte string.
   * 
   * @throws AvroTypeException If this is a stateful writer and a byte-string is
   *                           not expected
   */
  public abstract void writeBytes(byte[] bytes, int start, int len) throws IOException;

  /**
   * Writes a byte string. Equivalent to
   * <tt>writeBytes(bytes, 0, bytes.length)</tt>
   * 
   * @throws IOException
   * @throws AvroTypeException If this is a stateful writer and a byte-string is
   *                           not expected
   */
  public void writeBytes(byte[] bytes) throws IOException {
    writeBytes(bytes, 0, bytes.length);
  }

  /**
   * Writes a fixed size binary object.
   * 
   * @param bytes The contents to write
   * @param start The position within <tt>bytes</tt> where the contents start.
   * @param len   The number of bytes to write.
   * @throws AvroTypeException If this is a stateful writer and a byte-string is
   *                           not expected
   * @throws IOException
   */
  public abstract void writeFixed(byte[] bytes, int start, int len) throws IOException;

  /**
   * A shorthand for <tt>writeFixed(bytes, 0, bytes.length)</tt>
   * 
   * @param bytes
   */
  public void writeFixed(byte[] bytes) throws IOException {
    writeFixed(bytes, 0, bytes.length);
  }

  /** Writes a fixed from a ByteBuffer. */
  public void writeFixed(ByteBuffer bytes) throws IOException {
    int pos = bytes.position();
    int len = bytes.limit() - pos;
    if (bytes.hasArray()) {
      writeFixed(bytes.array(), bytes.arrayOffset() + pos, len);
    } else {
      byte[] b = new byte[len];
      bytes.duplicate().get(b, 0, len);
      writeFixed(b, 0, len);
    }
  }

  /**
   * Writes an enumeration.
   * 
   * @param e
   * @throws AvroTypeException If this is a stateful writer and an enumeration is
   *                           not expected or the <tt>e</tt> is out of range.
   * @throws IOException
   */
  public abstract void writeEnum(int e) throws IOException;

  /**
   * Call this method to start writing an array.
   *
   * When starting to serialize an array, call {@link #writeArrayStart}. Then,
   * before writing any data for any item call {@link #setItemCount} followed by a
   * sequence of {@link #startItem()} and the item itself. The number of
   * {@link #startItem()} should match the number specified in
   * {@link #setItemCount}. When actually writing the data of the item, you can
   * call any {@link Encoder} method (e.g., {@link #writeLong}). When all items of
   * the array have been written, call {@link #writeArrayEnd}.
   *
   * As an example, let's say you want to write an array of records, the record
   * consisting of an Long field and a Boolean field. Your code would look
   * something like this:
   * 
   * <pre>
   * out.writeArrayStart();
   * out.setItemCount(list.size());
   * for (Record r : list) {
   *   out.startItem();
   *   out.writeLong(r.longField);
   *   out.writeBoolean(r.boolField);
   * }
   * out.writeArrayEnd();
   * </pre>
   * 
   * @throws AvroTypeException If this is a stateful writer and an array is not
   *                           expected
   */
  public abstract void writeArrayStart() throws IOException;

  /**
   * Call this method before writing a batch of items in an array or a map. Then
   * for each item, call {@link #startItem()} followed by any of the other write
   * methods of {@link Encoder}. The number of calls to {@link #startItem()} must
   * be equal to the count specified in {@link #setItemCount}. Once a batch is
   * completed you can start another batch with {@link #setItemCount}.
   *
   * @param itemCount The number of {@link #startItem()} calls to follow.
   * @throws IOException
   */
  public abstract void setItemCount(long itemCount) throws IOException;

  /**
   * Start a new item of an array or map. See {@link #writeArrayStart} for usage
   * information.
   * 
   * @throws AvroTypeException If called outside of an array or map context
   */
  public abstract void startItem() throws IOException;

  /**
   * Call this method to finish writing an array. See {@link #writeArrayStart} for
   * usage information.
   *
   * @throws AvroTypeException If items written does not match count provided to
   *                           {@link #writeArrayStart}
   * @throws AvroTypeException If not currently inside an array
   */
  public abstract void writeArrayEnd() throws IOException;

  /**
   * Call this to start a new map. See {@link #writeArrayStart} for details on
   * usage.
   *
   * As an example of usage, let's say you want to write a map of records, the
   * record consisting of an Long field and a Boolean field. Your code would look
   * something like this:
   * 
   * <pre>
   * out.writeMapStart();
   * out.setItemCount(list.size());
   * for (Map.Entry<String, Record> entry : map.entrySet()) {
   *   out.startItem();
   *   out.writeString(entry.getKey());
   *   out.writeLong(entry.getValue().longField);
   *   out.writeBoolean(entry.getValue().boolField);
   * }
   * out.writeMapEnd();
   * </pre>
   * 
   * @throws AvroTypeException If this is a stateful writer and a map is not
   *                           expected
   */
  public abstract void writeMapStart() throws IOException;

  /**
   * Call this method to terminate the inner-most, currently-opened map. See
   * {@link #writeArrayStart} for more details.
   *
   * @throws AvroTypeException If items written does not match count provided to
   *                           {@link #writeMapStart}
   * @throws AvroTypeException If not currently inside a map
   */
  public abstract void writeMapEnd() throws IOException;

  /**
   * Call this method to write the tag of a union.
   *
   * As an example of usage, let's say you want to write a union, whose second
   * branch is a record consisting of an Long field and a Boolean field. Your code
   * would look something like this:
   * 
   * <pre>
   * out.writeIndex(1);
   * out.writeLong(record.longField);
   * out.writeBoolean(record.boolField);
   * </pre>
   * 
   * @throws AvroTypeException If this is a stateful writer and a map is not
   *                           expected
   */
  public abstract void writeIndex(int unionIndex) throws IOException;
}
